Event Structures
<!-- ##### SECTION Short_Description ##### -->
-
+data structures specific to each type of event.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The event structs contain data specific to each type of event in GDK.
</para>
<note>
<para>
</para>
-<!-- ##### STRUCT GdkEventAny ##### -->
-<para>
-Contains the fields which are common to all event structs.
-Any event can safely be cast to a #GdkEventAny to access these fields.
-</para>
-
-@type: the type of the event.
-@window: the window which received the event.
-@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-
-<!-- ##### STRUCT GdkEventExpose ##### -->
+<!-- ##### UNION GdkEvent ##### -->
<para>
-
+The #GdkEvent struct contains a union of all of the event structs,
+and allows access to the data fields in a number of ways.
</para>
-
-@type:
-@window:
-@send_event:
-@area:
-@count:
-
-<!-- ##### STRUCT GdkEventNoExpose ##### -->
<para>
-
+The event type is always the first field in all of the event structs, and
+can always be accessed with the following code, no matter what type of event
+it is:
+<informalexample>
+<programlisting>
+ GdkEvent *event;
+ GdkEventType type;
+
+ type = event->type;
+</programlisting>
+</informalexample>
</para>
-@type:
-@window:
-@send_event:
-
-<!-- ##### STRUCT GdkEventVisibility ##### -->
<para>
-
+To access other fields of the event structs, the pointer to the event can be
+cast to the appropriate event struct pointer, or the union member name can be
+used. For example if the event type is %GDK_BUTTON_PRESS then the x coordinate
+of the button press can be accessed with:
+<informalexample>
+<programlisting>
+ GdkEvent *event;
+ gdouble x;
+
+ x = ((GdkEventButton*)event)->x;
+</programlisting>
+</informalexample>
+or:
+<informalexample>
+<programlisting>
+ GdkEvent *event;
+ gdouble x;
+
+ x = event->button.x;
+</programlisting>
+</informalexample>
</para>
-@type:
-@window:
-@send_event:
-@state:
-<!-- ##### ENUM GdkVisibilityState ##### -->
+<!-- ##### STRUCT GdkEventAny ##### -->
<para>
-
+Contains the fields which are common to all event structs.
+Any event pointer can safely be cast to a pointer to a #GdkEventAny to access
+these fields.
</para>
-@GDK_VISIBILITY_UNOBSCURED:
-@GDK_VISIBILITY_PARTIAL:
-@GDK_VISIBILITY_FULLY_OBSCURED:
+@type: the type of the event.
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-<!-- ##### STRUCT GdkEventMotion ##### -->
+<!-- ##### STRUCT GdkEventKey ##### -->
<para>
-
+Describes a key press or key release event.
</para>
-@type:
-@window:
-@send_event:
-@time:
-@x:
-@y:
-@pressure:
-@xtilt:
-@ytilt:
-@state:
-@is_hint:
-@source:
-@deviceid:
-@x_root:
-@y_root:
+@type: the type of the event (%GDK_KEY_RELEASE or %GDK_KEY_RELEASE).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@time: the time of the event in milliseconds.
+@state: a bit-mask representing the state of the modifier keys (e.g. Control,
+Shift and Alt) and the pointer buttons. See #GdkModifierType.
+@keyval: the key that was pressed or released. See the <gdk/gdkkeysym.h>
+header file for a complete list of GDK key codes.
+@length: the length of @string.
+@string: a null-terminated multi-byte string containing the composed characters
+resulting from the key press. When text is being input, in a GtkEntry for
+example, it is these characters which should be added to the input buffer.
+When using <link linkend="gdk-Input-Methods"> Input Methods</link> to support
+internationalized text input, the composed characters appear here after the
+pre-editing has been completed.
<!-- ##### STRUCT GdkEventButton ##### -->
<para>
%GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
</para>
<para>
-Double and treble-clicks result in a sequence of events being received.
+Double and triple-clicks result in a sequence of events being received.
For double-clicks the order of events will be:
<orderedlist>
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
received just after the %GDK_BUTTON_PRESS.
</para>
<para>
-Treble-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS
+Triple-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS
is inserted after the third click. The order of the events is:
<orderedlist>
<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
</orderedlist>
</para>
+<para>
+For a double click to occur, the second button press must occur within 1/4 of
+a second of the first. For a triple click to occur, the third button press
+must also occur within 1/2 second of the first button press.
+</para>
-@type: the type of the event.
+@type: the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS,
+%GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE).
@window: the window which received the event.
@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-@time: the time of the event in milliseconds. This wraps around roughly every
-50 days.
+@time: the time of the event in milliseconds.
@x: the x coordinate of the mouse relative to the window.
@y: the y coordinate of the mouse relative to the window.
@pressure: the pressure of the button press, intended for input devices such
as graphics tablets. It defaults to 0.5.
+@xtilt: the horizontal tilt of the input device. Defaults to 0.
+@ytilt: the vertical tilt of the input device. Defaults to 0.
+@state: a bit-mask representing the state of the modifier keys (e.g. Control,
+Shift and Alt) and the pointer buttons. See #GdkModifierType.
+@button: the button which was pressed or released, numbered from 1 to 5.
+Normally button 1 is the left mouse button, 2 is the middle button,
+and 3 is the right button. On 2-button mice, the middle button can often
+be simulated by pressing both mouse buttons together.
+@source: the input device where the event came from, usually %GDK_SOURCE_MOUSE.
+@deviceid: the input device ID, usually %GDK_CORE_POINTER but may be
+different if touch screens or graphics tablets are being used.
+@x_root: the x coordinate of the mouse relative to the root of the screen.
+@y_root: the y coordinate of the mouse relative to the root of the screen.
+
+<!-- ##### STRUCT GdkEventMotion ##### -->
+<para>
+
+</para>
+
+@type: the type of the event.
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@time:
+@x:
+@y:
+@pressure:
@xtilt:
@ytilt:
@state:
-@button:
+@is_hint:
@source:
@deviceid:
-@x_root: the x coordinate of the mouse relative to the root of the screen.
-@y_root: the y coordinate of the mouse relative to the root of the screen.
+@x_root:
+@y_root:
-<!-- ##### STRUCT GdkEventKey ##### -->
+<!-- ##### STRUCT GdkEventExpose ##### -->
<para>
+Generated when all or part of a window becomes visible and needs to be
+redrawn.
+</para>
+@type: the type of the event (%GDK_EXPOSE).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@area: the area that needs to be redrawn.
+@count: the number of contiguous %GDK_EXPOSE events following this one.
+The only use for this is "exposure compression", i.e. handling all contiguous
+%GDK_EXPOSE events in one go, though GDK performs some exposure compression
+so this is not normally needed.
+
+<!-- ##### STRUCT GdkEventVisibility ##### -->
+<para>
+Generated when the window visibility status has changed.
</para>
-@type:
-@window:
-@send_event:
-@time:
-@state:
-@keyval:
-@length:
-@string:
+@type: the type of the event (%GDK_VISIBILITY_NOTIFY).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@state: the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED,
+%GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED).
+
+<!-- ##### ENUM GdkVisibilityState ##### -->
+<para>
+Specifies the visiblity status of a window for a #GdkEventVisibility.
+</para>
+
+@GDK_VISIBILITY_UNOBSCURED: the window is completely visible.
+@GDK_VISIBILITY_PARTIAL: the window is partially visible.
+@GDK_VISIBILITY_FULLY_OBSCURED: the window is not visible at all.
<!-- ##### STRUCT GdkEventCrossing ##### -->
<para>
</para>
-@type:
-@window:
-@send_event:
+@type: the type of the event.
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
@subwindow:
-@time:
+@time: the time of the event in milliseconds.
@x:
@y:
@x_root:
<!-- ##### STRUCT GdkEventFocus ##### -->
<para>
-
+Describes a change of keyboard focus.
</para>
-@type:
-@window:
-@send_event:
-@in:
+@type: the type of the event (%GDK_FOCUS_CHANGE).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@in: TRUE if the window has gained the keyboard focus, FALSE if it has lost
+the focus.
<!-- ##### STRUCT GdkEventConfigure ##### -->
<para>
-
+Generated when a window size or position has changed.
</para>
-@type:
-@window:
-@send_event:
-@x:
-@y:
-@width:
-@height:
+@type: the type of the event (%GDK_CONFIGURE).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@x: the new x coordinate of the window, relative to its parent.
+@y: the new y coordinate of the window, relative to its parent.
+@width: the new width of the window.
+@height: the new height of the window.
<!-- ##### STRUCT GdkEventProperty ##### -->
<para>
-
+Describes a property change on a window.
</para>
-@type:
-@window:
-@send_event:
-@atom:
-@time:
-@state:
+@type: the type of the event (%GDK_PROPERTY_NOTIFY).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@atom: the property that was changed.
+@time: the time of the event in milliseconds.
+@state: whether the property was changed (%GDK_PROPERTY_NEW_VALUE) or
+deleted (%GDK_PROPERTY_DELETE).
<!-- ##### ENUM GdkPropertyState ##### -->
<para>
-
+Specifies the type of a property change for a #GdkEventProperty.
</para>
-@GDK_PROPERTY_NEW_VALUE:
-@GDK_PROPERTY_DELETE:
+@GDK_PROPERTY_NEW_VALUE: the property value wan changed.
+@GDK_PROPERTY_DELETE: the property was deleted.
<!-- ##### STRUCT GdkEventSelection ##### -->
<para>
</para>
-@type:
-@window:
-@send_event:
+@type: the type of the event.
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
@selection:
@target:
@property:
@requestor:
-@time:
+@time: the time of the event in milliseconds.
-<!-- ##### STRUCT GdkEventProximity ##### -->
+<!-- ##### STRUCT GdkEventDND ##### -->
<para>
</para>
-@type:
-@window:
-@send_event:
-@time:
-@source:
-@deviceid:
+@type: the type of the event.
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@context:
+@time: the time of the event in milliseconds.
+@x_root:
+@y_root:
-<!-- ##### STRUCT GdkEventClient ##### -->
+<!-- ##### STRUCT GdkEventProximity ##### -->
<para>
</para>
-@type:
-@window:
-@send_event:
-@message_type:
-@data_format:
+@type: the type of the event.
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@time: the time of the event in milliseconds.
+@source:
+@deviceid:
-<!-- ##### STRUCT GdkEventDND ##### -->
+<!-- ##### STRUCT GdkEventClient ##### -->
<para>
-
+An event sent by another client application.
</para>
-@type:
-@window:
-@send_event:
-@context:
-@time:
-@x_root:
-@y_root:
+@type: the type of the event (%GDK_CLIENT_EVENT).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@message_type: the type of the message, which can be defined by the
+application.
+@data_format: the format of the data, given as the number of bits in each
+data element, i.e. 8, 16, or 32. 8-bit data uses the b array of the data
+union, 16-bit data uses the s array, and 32-bit data uses the l array.
-<!-- ##### UNION GdkEvent ##### -->
+<!-- ##### STRUCT GdkEventNoExpose ##### -->
<para>
-
+Generated when the area of a #GdkDrawable being copied, with gdk_draw_pixmap()
+or gdk_window_copy_area(), was completely available.
</para>
-
-
-<!-- ##### TYPEDEF GdkXEvent ##### -->
<para>
-
+FIXME: add more here.
</para>
+@type: the type of the event (%GDK_NO_EXPOSE).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
projects / gtk4.git / commitdiff